/*-------------------------------------------------------------------------
 *
 * tidbitmap.h
 *	  PostgreSQL 元组标识符（TID）位图包
 *
 * 此模块提供的位图数据结构在精神上
 * 类似于 Bitmapsets，但特别适用于存储
 * 元组标识符（TIDs）或 ItemPointers 的集合。
 * 特别地，ItemPointer 被分为 BlockNumber 和 OffsetNumber。
 * 此外，由于我们希望能够在内存中存储非常大的元组集，
 * 用此数据结构，我们支持“有损”存储，其中我们
 * 不再记住页面上的单个元组偏移，只记住特定页面需要访问的事实。
 *
 *
 * Copyright (c) 2003-2022, PostgreSQL Global Development Group
 *
 * src/include/nodes/tidbitmap.h
 *
 *-------------------------------------------------------------------------
 */
#ifndef TIDBITMAP_H
#define TIDBITMAP_H

#include "storage/itemptr.h"
#include "utils/dsa.h"


/*
 * 实际的位图表示是 tidbitmap.c 的私有部分。 调用者可以在其上执行 IsA(x, TIDBitmap)，但不能做其他操作。
 */
typedef struct TIDBitmap TIDBitmap;

/* 同样，TBMIterator 是私有的 */
typedef struct TBMIterator TBMIterator;
typedef struct TBMSharedIterator TBMSharedIterator;

/* tbm_iterate 的结果结构 */
typedef struct TBMIterateResult
{
	BlockNumber blockno;		/* 包含元组的页面编号 */
	int			ntuples;		/* -1 表示有损结果 */
	bool		recheck;		/* 元组是否需要重新检查？ */
	/* 注意：如果 ntuples < 0，则检查总是为真 */
	OffsetNumber offsets[FLEXIBLE_ARRAY_MEMBER];
} TBMIterateResult;

/* nodes/tidbitmap.c 中的函数原型 */

extern TIDBitmap *tbm_create(long maxbytes, dsa_area *dsa);
extern void tbm_free(TIDBitmap *tbm);
extern void tbm_free_shared_area(dsa_area *dsa, dsa_pointer dp);

extern void tbm_add_tuples(TIDBitmap *tbm,
						   const ItemPointer tids, int ntids,
						   bool recheck);
extern void tbm_add_page(TIDBitmap *tbm, BlockNumber pageno);

extern void tbm_union(TIDBitmap *a, const TIDBitmap *b);
extern void tbm_intersect(TIDBitmap *a, const TIDBitmap *b);

extern bool tbm_is_empty(const TIDBitmap *tbm);

extern TBMIterator *tbm_begin_iterate(TIDBitmap *tbm);
extern dsa_pointer tbm_prepare_shared_iterate(TIDBitmap *tbm);
extern TBMIterateResult *tbm_iterate(TBMIterator *iterator);
extern TBMIterateResult *tbm_shared_iterate(TBMSharedIterator *iterator);
extern void tbm_end_iterate(TBMIterator *iterator);
extern void tbm_end_shared_iterate(TBMSharedIterator *iterator);
extern TBMSharedIterator *tbm_attach_shared_iterate(dsa_area *dsa,
													dsa_pointer dp);
extern long tbm_calculate_entries(double maxbytes);

#endif							/* TIDBITMAP_H */
